home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 122_01 / tutorial < prev    next >
Text File  |  1984-03-05  |  13KB  |  418 lines
  1. TUTORIAL (headings are approximate):
  2. copyright (C) 1983 by E. E. Bergmann
  3. General, the prompt and stack.
  4. Using memory, constants and variables.
  5. Simple i/o, defining new words.
  6. Iteration and conditional.
  7. Numerical i/o.
  8. Redefining and FORGET.
  9. The editor.
  10. ::
  11. :::
  12. *********************************************************
  13. *                            *
  14. * PISTOL-Portably Implemented Stack Oriented Language    *
  15. *            Version 2.0            *
  16. * (C) 1983 by    Ernest E. Bergmann            *
  17. *        Physics, Building #16            *
  18. *        Lehigh Univerisity            *
  19. *        Bethlehem, Pa. 18015            *
  20. *                            *
  21. * Permission is hereby granted for all reproduction and *
  22. * distribution of this material provided this notice is *
  23. * included.                        *
  24. *                            *
  25. *********************************************************
  26. ::
  27. :::
  28. [A carriage return will continue the scroll;
  29. a "Q" and then a carriage return will abort]
  30.     Before discussing some examples and features, it is
  31. probably best to understand the "prompt".  The prompt is what a
  32. program types at the beginning of the line when it is awaiting
  33. input from the user.  The prompt supplied by PISTOL can be
  34. several characters long and it is to inform or remind the user
  35. about the "state" of the program.  If a number appears at the
  36. beginning of the prompt, it signifies that the parameter stack
  37. is not empty.  Next, a letter is displayed (such as "X") that
  38. indicates the current number base used for i/o ("X", the Roman
  39. numeral for "10", signifies decimal). After this letter there
  40. may be other characters or symbols that are used to indicate if
  41. you are in the middle of some syntactical construction.
  42. Finally, the ">" completes the prompt expression.  In the
  43. examples supplied above and below we have attempted to suggest
  44. the typical prompts that one might expect to see.
  45.  
  46.     After educating PISTOL by loading PBASE2 or by
  47. restoring CORE2, the system is "smarter" you can try the
  48. following examples:
  49.  
  50. X> 1 2 23 STACK
  51.  
  52. The system takes each number as encountered and places them on
  53. the stack.  The word, STACK , prints the current contents of
  54. the stack without changing the stack in any way.
  55.  
  56.     Now try typing:
  57. 3X> + STACK
  58.  
  59. This should result in the addition of the top two members of
  60. the stack (2 and 23) and placing the result (answer 25) back on
  61. the stack. The word STACK then displays the current contents of
  62. the stack.
  63.  
  64.     Now try typing:
  65. 2X> * stack
  66.  
  67. The top two items of the stack will be multiplied together and
  68. the result left on the stack.  The word, "stack" is interpreted
  69. as STACK, and we see that the only thing on the stack is the
  70. answer 25.
  71.  
  72.     To disable the automatic interpretation of lowercase
  73. as uppercase, type:
  74.  
  75. X> RAISE OFF (or "raise off")
  76.  
  77. and successive lines will be interpreted without conversion of
  78. lowercase to uppercase.  To revert to conversion, type:
  79.  
  80. X> RAISE ON
  81.  
  82.     There are a number of different options that can be
  83. invoked such as ECHO ON and ECHO OFF which control the listing
  84. of files read in by the '<filename> LOAD operation.  One can
  85. use CONSOLE ON and CONSOLE OFF to determine what reaches the
  86. terminal.  An error condion will automatically restore output
  87. to the terminal.  LIST ON and LIST OFF will determine what
  88. output will also be routed to the output list file(of course a
  89. listfile has to be declared first).  This is useful to have a
  90. more permanent record of what happened during a session.  There
  91. is also a SHOWCODE and a NOSHOWCODE which will show the results
  92. of compiling each input line (that is for those who want or
  93. like to know what is going on behind the scenes).
  94.  
  95.     On the DEC-20 (and also in CP/M) one can exit from
  96. PISTOL by using a control-C, but a more "refined" way is to
  97. type the word, BYE, which will return you to the operating
  98. system.
  99. ::
  100. :::
  101.     PISTOL can examine the contents of its own (virtual)
  102. memory. The W@ ("fetch") operator is similar in spirit to
  103. the PEEK function in BASIC.  To place the contents of a
  104. memory location on the stack one simply places the address
  105. on stack and then types W@ .  For example, if we want to
  106. place on the stack the current value of RADIX, the base used
  107. in all I/O number conversion, we need to find the value
  108. stored in the RAM location at USER (i.e. what is RAM[USER]?)
  109. we can type:
  110.  
  111. X> USER W@
  112.  
  113. which will place the desired information on stack.  The inverse
  114. operation, which is more dangerous(because a mistake can crash
  115. the program), is to store a new value in the RADIX, hence
  116. change the number base.  The operator, W! ("word store"),
  117. performs this function(for this example we suppose that the
  118. RADIX address is 12345 decimal, usually, it is not):
  119.  
  120. X> 16 12345 W!
  121.  
  122. would convert PISTOL to converse in hexadecimal.
  123.  
  124.     Of course it is awkward to remember constants, such
  125. as the address of RADIX so we can define such constants by:
  126.  
  127.  > DECIMAL
  128. X> 12345 'RADIX CONSTANT
  129.  
  130. After such a CONSTANT definition we can redo the examples that
  131. use W@ and W! by (RADIX is in fact already defined in PBASE2):
  132.  
  133. X> RADIX W@
  134. and
  135. X> 16 RADIX W!
  136.  
  137.     As an additional convenience the user can define space
  138. for variables with the word, VARIABLE.  For example, If you
  139. wish to define a variable with the initial value 0 and named
  140. ANSWER, you should type:
  141.  
  142. X> 0 'ANSWER VARIABLE
  143.  
  144. Later, if you wish to perform the PASCAL statement:
  145.  
  146. ANSWER := ANSWER + 1;
  147.  
  148. you would write the PISTOL code:
  149.  
  150. X> ANSWER W@ 1 + ANSWER W!
  151.  
  152. Notice that you MUST choose an initial value in VARIABLE and,
  153. of course, CONSTANT definitions.
  154.  
  155.     Just like the convenience feature of PASCAL,
  156. for which one can use SUCC(ANSWER) to increment ANSWER
  157. by one, there exists an analogous operator (or you can
  158. define your own!):
  159.  
  160. X> ANSWER 1+W!
  161.  
  162. ::
  163. :::
  164.     The language has many resources beyond those
  165. presented so far.  Perhaps the most significant is the
  166. ability to define new words or definitions to make the
  167. language increasingly smarter. Try examining the contents of
  168. the file, PBASE2 , to see how the definitions may be formed.
  169. As a complex example, the word, = is defined whose function
  170. is to take the top item off of the stack and print its
  171. value.  For example, typing:
  172.  
  173. X> 8 8 + =
  174.  
  175. will cause the system to respond with the answer: 16.  Note
  176. that this calculation causes no net change to the stack (it
  177. is the presence of a number before "X>" that indicates the
  178. number of items in the stack at that moment); its contents
  179. before the first "8" was typed is the same as its contents
  180. after the system responds with 16.  Thus the definition of
  181. the word = has increased the convenience of the system for
  182. arithmetic calculations.
  183.  
  184.     The system can and does handle strings.  Suppose you
  185. would like the system to output "HELLO".  Try typing:
  186.  
  187. X> 'HELLO MSG
  188.  
  189. The system will take the 'HELLO as a string to be placed upon
  190. the stack.  The MSG ,"message" takes the top item off of the
  191. stack, assumes it to be a string, and prints it.  The stack
  192. contains the same stuff after MSG is executed as before the
  193. 'HELLO was typed.
  194.  
  195.     Useful I/O words are CR which will output a carriage
  196. return and line feed sequence.  The word SPACE will output a
  197. space. And the word SPACES will pop the top of stack to obtain
  198. the number of spaces to be output.  For example:
  199.  
  200. X> 'HELLO MSG SPACE 'HELLO MSG CR 5 SPACES 'BYE MSG
  201.  
  202. should produce:
  203.  
  204. HELLO HELLO
  205.      BYE
  206.  
  207.  
  208.     Standard output would be most tedious if we could not
  209. create definitions to speed up programming.  Here is a humorous
  210. example:
  211.  
  212. X> 'HELLO : 'HELLO, MSG SPACE 'YOURSELF! CR ;
  213.  
  214. The use of : and ; provide the means to define a new word
  215. "HELLO" Later, you can type:
  216.  
  217. X> HELLO
  218.  
  219. and the system will respond:
  220.  
  221. HELLO, YOURSELF!
  222.  
  223.     Thus we see that the pair of symbols, ":" and ";"
  224. delineate a structure used to make definitions.  The material
  225. in between the two symbols becomes the definition of the word
  226. whose name is the string that was lastly placed on the stack
  227. before the ":".
  228.  
  229.     One can create strings with embedded blanks and tabs up
  230. to 127 characters long by using double quotes to delineate both
  231. ends of the string.  For example, the word, HELLO, defined
  232. above, could have been defined:
  233.  
  234. 'HELLO : "HELLO, YOURSELF!" MSG CR ;
  235.  
  236. Ev